ObjectWindows 
Copyright (c) 1996 Borland International

Title: TOOLTIP Example

Keywords: TTooltip;Common control

TTooltip, An Introduction
=========================
The TTooltip class encapsulates a tooltip control - a small
pop-up window that displays a single line of descriptive text
giving the purpose of tools in an application. The tools is
either a window, such as a child window or control, or an
application-defined rectangular area within a window's client
area. The tooltip control appears only when the user puts the
cursor on a tool and leaves it there for approximately one-half
second. The tooltip control appears near the cursor and
disappears when the user clicks a mouse button or move the
cursor off the tool.


Creating a TTooltip Object
==========================
The TTooltip class offers two constructor: one for creating a
brand new tooltip control and one for aliasing an existing
control. The following code fragment illustrates how to create a
tooltip control.

    void TMyWindow::SetupWindow()
    {
        TWindow::SetupWindow();

        tooltip = new TTooltip(this);
        tooltip->Create();
    }
        

Specifying Tools to the tooltip Control
======================================= 
Once you created a tooltip, you must specify the tools for which
the control must display a descriptive message. To add a new
tool you must first fill a TToolInfo which describes the tool.
Each tool must have a integer which uniquely identifies that
tool.  For example, the following code designates a rectangular
area of a window as a tool.

    void
    TMyWindow::AddTopLeftTool()
    {
        uint toolId = ID_TOPLEFT_TOOL;      // Tool ID
        TRect rect(0, 0, 20, 20);           // Tool Rectangle
        TToolInfo ti(this, rect, ID_TOPLEFT_TOOL);
        tooltip->AddTool(ti);
    }


Providing the Tooltip Text 
========================== 
When adding a tool you may provide the text to be used when
describing the tool as the last parameter to the constructor of
the TToolInfo structure. For example,

        TToolInfo ti(this, rect, ID_TOPLEFT_TOOL, "Top Left");
        tooltip->AddTool(ti);

However, you may opt to provide the text on demand. This allows
you to customize the message display to the user. The
EV_TTN_NEEDTEXT macro allow you to specify a member function
which can provide the text at runtime. The following code
snippet illustrates:
  
    class TMyWindow : public TWindow {
        //
        // Additional definition ommitted for clarity
        //
        protected:
            void    HandleTooltipText(TTooltipText& tiTxt);
    };

    DEFINE_RESPONSE_TABLE1(TMyWindow, TWindow)
        EV_TTN_NEEDTEXT(ID_TOPLEFT_TOOL, HandleTooltipText),
    END_RESPONSE_TABLE;


    void
    TMyWindow::HandleTooltipText(TTooltipText& tiTxt)
    {
        tiTxt.CopyText("Top Left square");
    }


Additional Information
======================
1. The notification handler of the ObjectWindows TDecoratedFrame
class enhances the mechanism for specifying the tooltip text by
sending a 'TTooltipEnabler' up the command chain. This allows
the 'context' window to provide the text even if it did not
setup the tool. For example, a grid control in focus can
customize the cut, paste and copy tools to specify the data type
being manipulated. ['copy cell' instead of just 'copy'].

2. The EvCommandEnable handler of TDecoratedFrame attempts to
provide the tooltip text by looking in two locations:

(a) First the window's menu is scanned for a menuitem with an id
corresponding to that of the tool. If found, the menustring is
provided.

(b) Next, TDecoratedFrame attempts to load a string resource
with an id corresponding to that of the tool. If found, the
string is scanned for a line-feed character. If successful,
TDecoratedFrame provides the string following the line-feed as
tooltip text.

NOTE: You should structure you hint text string using the
following format:
 <string to be displayed on statusbar>\n<tooltip hint text>